Summary

CodeBurn already gives strong post-hoc cost visibility, but there was no small command for catching runaway spend while it is happening. This adds codeburn guard, a one-shot local guardrail check that flags sessions or local-hour windows once they reach configurable USD thresholds.

What changed

• add codeburn guard with default thresholds of $3 per session and $10 per local hour
• support existing report-style filters: --period, --from, --to, --provider, --project, and --exclude
• add --json for scripts and --fail-on-alert for cron/CI workflows
• aggregate hourly spend from parsed assistant calls using local timezone bucketing
• sort alerts by threshold severity so the most urgent guardrail breach appears first
• document the command and add an Unreleased changelog entry

Why one-shot first

A daemon/watch mode could come later, but a one-shot command keeps this first version small and composable. Users can run it manually, from cron, or inside shell scripts without introducing background process state or notification preferences in this PR.

Example

codeburn guard
codeburn guard -p week --max-session-usd 5 --max-hourly-usd 20
codeburn guard --json --fail-on-alert

Validation

• npx vitest run tests/guard.test.ts
• npx vitest run
• npm run build
• node dist/cli.js guard --help
• node dist/cli.js guard --from 2999-01-01 --to 2999-01-02 --json

Note: full npx tsc --noEmit is currently blocked on origin/main by existing src/providers/copilot.ts type errors; this branch does not touch that provider.